home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.5 Complementary Applications 2004 February / SGI IRIX 6.5 Complementary Applications 2004 February.iso / dist / cde.idb / usr / dt / share / man / cat3 / pam.z.z / pam.z
Encoding:
Text File  |  2003-11-18  |  7.0 KB  |  243 lines
  1. .\" Sccs id goes here
  2. '\"macro stdmacro
  3. .\" Copyright (c) 1995, Sun Microsystems, Inc. 
  4. .\" All Rights Reserved
  5. .nr X
  6. .TH pam 3 "19 October 1995"
  7. .SH NAME
  8. PAM \- Pluggable Authentication Module
  9. .SH SYNOPSIS
  10. .LP
  11. .nf
  12. .ft 3
  13. #include <security/pam_appl.h>
  14. .ft
  15. .fi
  16. .LP
  17. .B cc
  18. .RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
  19. .B \-lpam
  20. .RI "[ " "library" " \|.\|.\|. ]"
  21. .LP
  22. .SH DESCRIPTION
  23. .IX "PAM" "" "\fLPAM\fP \(em Pluggable Authentication Module"
  24. .PP
  25. .B PAM
  26. gives system administrators the flexibility of choosing any authentication
  27. service available on the system to perform authentication.  The framework
  28. also allows new authentication service modules to be plugged in and made
  29. available without modifying the applications.
  30.  
  31. The
  32. .B PAM
  33. framework,
  34. .B libpam,
  35. consists of an interface library and multiple authentication 
  36. service modules.  The
  37. .B PAM
  38. interface library is the layer implementing the 
  39. Application Programming Interface (API).  The authentication service modules
  40. are a set of dynamically loadable objects invoked by the
  41. .B PAM
  42. API to provide a particular type of user authentication.
  43. .SS Interface Overview
  44. The
  45. .B PAM
  46. library interface
  47. consists of functions which can be grouped into five categories.  The
  48. names for all the authentication library functions start with
  49. .B pam_.
  50. .PP
  51. The first category contains functions for establishing and terminating an 
  52. authentication activity
  53. .B (pam_start(3)
  54. and
  55. .B pam_end(3)), 
  56. functions to maintain module specific data
  57. .B (pam_[sg]et_data(3)),
  58. functions to maintain state information
  59. .B (pam_[sg]et_item(3)),
  60. and a function to return error status information
  61. .B (pam_strerror(3)).
  62. .PP
  63. The second category contains functions to authenticate an individual user
  64. .B (pam_authenticate(3))
  65. and to set the credentials of the user
  66. .B (pam_setcred(3)).
  67. .PP
  68. The third category contains functions to do account management
  69. .B (pam_acct_mgmt(3)).
  70. This includes checking for password aging and access-hour restrictions.
  71. .PP
  72. The fourth category contains functions to perform session management
  73. .B (pam_open_session(3)
  74. and
  75. .B (pam_close_session(3))
  76. after access to the system has been granted.
  77. .PP
  78. The fifth category consists of functions to change authentication tokens
  79. .B (pam_chauthtok(3)).
  80. An authentication token is the object used to verify the
  81. identity of the user.  In UNIX, an authentication
  82. token is a user's password.
  83. .PP
  84. All the
  85. .B pam_*()
  86. interfaces are implemented through the library
  87. .B libpam.
  88. For each of the categories listed above, excluding the first category
  89. .B (pam_start(), pam_end(), 
  90. .B pam_[sg]et_data(),
  91. .B pam_[sg]et_item(),
  92. and
  93. .B pam_strerror())
  94. there exists a dynamically loadable shared module that provides the appropriate 
  95. service layer functionality upon demand.  The functional entry points in the 
  96. service layer start with the 
  97. .B pam_sm_
  98. prefix.  The only difference between the
  99. .B pam_sm_*()
  100. interfaces and their corresponding
  101. .B pam_
  102. interfaces is that all the
  103. .B pam_sm_*()
  104. interfaces require extra parameters to pass service specific options
  105. to the shared modules.  
  106. Please refer to
  107. .BR pam_sm(3)
  108. for an overview of the PAM service module APIs.
  109.  
  110. .SS Stateful Interface
  111. A sequence of calls sharing a common set of state information
  112. is referred to as an authentication transaction.  An authentication 
  113. transaction begins with a call to
  114. .B pam_start().  pam_start()
  115. allocates space, performs various initialization activities,
  116. and assigns a PAM authentication handle to be used for subsequent calls
  117. to the library.  
  118.  
  119. After initiating an authentication transaction, applications can invoke
  120. .B pam_authenticate() 
  121. to authenticate a particular user, and
  122. .B pam_acct_mgmt()
  123. to perform system entry management (the
  124. application may want to determine if the user's 
  125. password has expired).
  126.  
  127. If the user has been successfully authenticated, applications call 
  128. .B pam_setcred()
  129. to set any user credentials associated with the authentication service.
  130. The calls to
  131. .B pam_start(),
  132. .B pam_authenticate()
  133. and
  134. .B pam_setcred()
  135. must be made with the same authentication handle
  136. returned by
  137. .B pam_start().
  138. This is necessary because during the call to
  139. .B pam_authenticate(),
  140. service modules may store module-specific data in the handle
  141. that is intended for use by
  142. .B pam_setcred().
  143.  
  144. To perform session management, applications call
  145. .B pam_open_session().
  146. For example, the system may want to store 
  147. the total time for the session.  The function
  148. .B pam_close_session()
  149. closes the current session.
  150.  
  151. When necessary, applications can call
  152. .B pam_get_item()
  153. and
  154. .B pam_set_item()
  155. to access and update specific authentication information.
  156. Such information may include the current username.
  157.  
  158. To terminate an authentication transaction, the application simply calls
  159. .B pam_end(),
  160. which frees previously allocated space used to store authentication information.
  161. .PP
  162. .SS Application - Authentication Service Interactive Interface
  163. The authentication service in
  164. .B PAM
  165. does not communicate directly with the user; instead it
  166. relies on the application to perform all such interactions.
  167. The application passes a pointer to the function,
  168. .B conv(),
  169. along with any associated application data pointers, through a
  170. .IR pam_conv
  171. structure to the authentication service when it initiates
  172. an authentication transaction (via a call to
  173. .B pam_start()).
  174. The service will then use the function
  175. .B (conv())
  176. to prompt the user for data, 
  177. output error messages, and display text information.  Refer to
  178. .B pam_start(3)
  179. for more information.
  180.  
  181. .SS Stacking Multiple Schemes
  182. The
  183. .B PAM
  184. architecture enables authentication by multiple authentication services through
  185. .I stacking.
  186. System entry applications, such as
  187. .B login(1),
  188. stack multiple service modules to authenticate users with multiple
  189. authentication services.  The order in which authentication service 
  190. modules are stacked is specified in the configuration file,
  191. .B pam.conf(4).
  192. A system administrator determines this ordering, and also determines 
  193. whether the same password can be used for all authentication services.  
  194.  
  195. .SS Administrative Interface    
  196. The authentication libraries,
  197. .B /usr/lib/libpam.so.1
  198. and
  199. .B /usr/lib/libpam.a,
  200. implement the framework interface.  Various authentication services are 
  201. implemented by their own loadable modules whose paths are specified through the
  202. .B pam.conf(4)
  203. file.
  204. .PP
  205. .SH "RETURN VALUES"
  206. .PP
  207. The
  208. .B PAM
  209. functions may return one of the following generic values, 
  210. or one of the values defined in the specific man pages:
  211. .RS
  212. .IP "PAM_SUCCESS" 22
  213. Successful function return
  214. .IP "PAM_OPEN_ERR" 22
  215. Dlopen() failure when dynamically loading a service module
  216. .IP "PAM_SYMBOL_ERR" 22
  217. Symbol not found
  218. .IP "PAM_SERVICE_ERR" 22 
  219. Error in service module
  220. .IP "PAM_SYSTEM_ERR" 22
  221. System error
  222. .IP "PAM_BUF_ERR" 22
  223. Memory buffer error
  224. .IP "PAM_CONV_ERR" 22
  225. Conversation failure
  226. .IP "PAM_PERM_DENIED
  227. Permission denied
  228. .RE
  229.  
  230. .SH "SEE ALSO"
  231. .BR pam_authenticate (3),
  232. .BR pam_open_session (3),
  233. .BR pam_chauthtok (3),
  234. .BR pam_set_item (3),
  235. .BR pam_setcred (3),
  236. .BR pam_sm (3),
  237. .BR pam_start (3),
  238. .BR pam_strerror (3),
  239. .BR pam.conf (4)
  240. .SH WARNING
  241. Please note that all the PAM APIs and the data structures are subject to
  242. change without notice.
  243.